import type { IBaseEntity } from '../common/base';
import type { StudentStatusEnum } from './enums';

/**
 * 学生实体接口
 * @description 学生的完整信息结构
 */
export interface IStudent extends IBaseEntity {
  /** 学生姓名 */
  name: string;
  /** 学号 */
  studentId: string;
  /** 年级 */
  grade?: string;
  /** 班级 */
  class?: string;
  /** 联系电话 */
  phone?: string;
  /** 家长姓名 */
  parentName?: string;
  /** 家长联系电话 */
  parentPhone?: string;
  /** 学生年龄 */
  age?: number;
  /** 性别 */
  gender?: 'male' | 'female' | 'other';
  /** 出生日期 */
  birthDate?: string;
  /** 家庭住址 */
  address?: string;
  /** 邮箱地址 */
  email?: string;
  /** 备注信息 */
  remark?: string;
  /** 学生状态 */
  status: StudentStatusEnum;
  /** 头像URL */
  avatar?: string;
  /** 入学日期 */
  enrollmentDate?: string;
  /** 毕业日期 */
  graduationDate?: string;
}

/**
 * 学生创建请求
 * @description 创建学生时需要的数据
 */
export type IStudentCreateRequest = Omit<IStudent, 'id' | 'createdAt' | 'updatedAt'>;

/**
 * 学生更新请求
 * @description 更新学生信息时的数据
 */
export type IStudentUpdateRequest = Partial<IStudentCreateRequest> & {
  /** 学生ID */
  id: string;
};

/**
 * 学生查询参数
 * @description 查询学生时的筛选条件
 */
export interface IStudentQueryParams {
  /** 学生姓名（模糊搜索） */
  name?: string;
  /** 学号 */
  studentId?: string;
  /** 年级 */
  grade?: string;
  /** 班级 */
  class?: string;
  /** 学生状态 */
  status?: StudentStatusEnum;
  /** 性别 */
  gender?: 'male' | 'female' | 'other';
  /** 年龄范围 - 最小年龄 */
  minAge?: number;
  /** 年龄范围 - 最大年龄 */
  maxAge?: number;
  /** 入学日期范围 - 开始日期 */
  enrollmentStartDate?: string;
  /** 入学日期范围 - 结束日期 */
  enrollmentEndDate?: string;
}

/**
 * 学生统计信息
 * @description 学生相关的统计数据
 */
export interface IStudentStatistics {
  /** 学生总数 */
  totalCount: number;
  /** 在读学生数 */
  activeCount: number;
  /** 休学学生数 */
  inactiveCount: number;
  /** 毕业学生数 */
  graduatedCount: number;
  /** 按年级分组统计 */
  gradeDistribution: Array<{
    grade: string;
    count: number;
  }>;
  /** 按班级分组统计 */
  classDistribution: Array<{
    class: string;
    count: number;
  }>;
  /** 按性别分组统计 */
  genderDistribution: Array<{
    gender: 'male' | 'female' | 'other';
    count: number;
  }>;
}

/**
 * 学生简要信息
 * @description 用于列表显示的学生简要信息
 */
export interface IStudentSummary {
  /** 学生ID */
  id: string;
  /** 学生姓名 */
  name: string;
  /** 学号 */
  studentId: string;
  /** 年级 */
  grade?: string;
  /** 班级 */
  class?: string;
  /** 学生状态 */
  status: StudentStatusEnum;
  /** 头像URL */
  avatar?: string;
}